 |
GeMA
The GeMA main application
|
Loading...
Searching...
No Matches
|
GeMA
The GeMA main application
|
This tutorial presents a step by step guide on how to build the GeMA framework on the Windows platform.
The current official development environment uses Visual Studio 2022, but the code also compiles fine with Visual Studio 2019 (and probably 2017). See comments on the compiler version below.
It is also necessary to install the Qt library. Currently the development version is based on Qt 5.15.2 (the latest non comercial version of Qt 5). Any revision later than 5.12.x should be compatible. The Open source version of Qt can be downloaded from http://www.qt.io/download/
For compiling the iterative numerical solver plugin, based on the Lis library, you will need the header files for the Windows 7.1A SDK. If you have an old Visual studio installation (like VS2013) in your machine, those headers will already be in place. Otherwise, you can install them by enabling the "Windows XP support for C++" option in the Visual Studio 2017 installation. Using Visual Studio 2022 is also possible. It will requires the components
For compiling the SuiteSparse numerical solver plugin (home of the CHOLMOD, UMFPACK and other solvers), you will also need to install the CMake tool on your environment. The minimum required version is 3.22. If you wan't those solvers to have CUDA support (used by the CHOLMOD and SPQR solvers), you MUST install the NVIDIA compilers prior to the first compilation of GeMA. It will (hopefully) be discovered automatically by GeMA through the CUDA_PATH environment variable.
If you want to enable the multi-grid SAAMG pre-conditioner, also from the Lis library, you will need to have installed the Intel Fortran environment on your machine. That is not required, but fortunatelly, installing it is quite easy. Just download the "Intel Fortran Compiler Classic and Intel Fortran Compiler for Windows" package from the link below and follow the instructions.
You will also need to have the SVN command line tools installed in your environment. The 'svnversion' command is used in the build process. It can be installed by the Tortoise SVN installer if you select the command line tools option. Alternatively (if you don't have access to the GeMA SVN, for example), you can pass the -nosvn command line option when calling the vc_build.bat command on step 3.2 to bypass this requirement.
When installing Qt, make sure to select the matching Visual Studio 64 bits version to your compiler. If compiling with Visual studio 2022, select the 2019 library version. You also need to select the QtCharts package if you want to build the "GeMA Monitor" application (you can pass the -nomonitor flag to step 3.2 if you don't want to build the monitor app).
Tip 1: After installing the Visual Studio environment, it can be updated by the "Check for updates" item in the "Help" menu.
Tip 2: Installing the "NPL Lua language Service" package helps editing Lua files in Visual studio. Go to the "Extensions and Updates" dialog from the "Tools" menu. In that dialog, select the "Online" item on the left tree. Next, go to the "search" box on the top right, type "npl" and press Enter. Select the "NPL_LuaLanguageService" package and click in the "Download" button. The installation will happen after closing the development environment.
Tip 3: Instaling the Qt Visual Studio Add-in greatly improves debugging experience. To install, just follow the instructions in Tip 2, searching for "Qt" instead. After installing, the path to the Qt distribution should be set through the "Qt options" item in the "Qt VS Tools" menu.
(The tips above where described for Visual studio 2017. The menu items may change a little for newer versions, but the tips are still valid)
The Gema compilation should be started through a command prompt with an environment with variables set for using Qt and Visual Studio in 64 bits mode. If you intend to use the SAAMG pre-conditioner, you will also need a configured Fortran environment.
One way to do that is to create a bat file named qtenv_vs20xx_64.bat containing the following code (please, check given paths and update them as needed):
Note that Visual Studio path follows the pattern
For visual studio 2022 Community it would be:
If you are using the 2022 Community version to compile the code with the 2019 compiler, you will need to pass the -vcvars_ver=14.29 flag to the bat file, so your call line should become:
(see https://learn.microsoft.com/en-us/cpp/build/building-on-the-command-line?view=msvc-170)
Note that this parameter is NOT needed if you are going to compile with the 2022 compiler!
Also note that the Fortran environment is optional, as discussed above.
An interesting place to put this file is in the Qt distribution, inside the C:\Qt\5.15.2\msvc2019_64 directory (update paths as needed).
After opening a command prompt, just run the bat to setup the environment. This can be easily automated by a shortcut having as target:
COMSPEC% /K C:\FULL_PATH_TO_THE_BAT_FILE\qtenv_vs2022_64.bat
Setting the "Start in" option for the shortcut to your GeMA installation also helps.
IMPORTANT: If you followed the instructions above to create your compilation environment, please make sure that you are using the COMMAND PROMPT to run your bat file and NOT Windows Power Shell. Power shell uses a different syntax for setting environment variables and a plain SET, as used by our bat, visual studio bat and intel fortran bats will not work!!!!
Inside Tecgraf, the code can be downloaded from the following SVN repository:
https://subversion.tecgraf.puc-rio.br/svn/gema/trunk
3.1) Open up a command prompt with the build environment set as explained previously.
3.2) On the root folder of your GeMA distribution, run the vc_build.bat command. This will prepare Visual Studio projects and build some external libraries that are changed very rarely.
Files should be added to the project always by way of .pro files and never directlly to a visual studio project. So, it is important to run the vc_build.bat command after every code update from the source repository. Don't worry though. This is normally a quick step. The initial compilation, which takes a little time, only happens on the first time that vc_build.bat is executed (or in the rare ocassion of a change in external libraries).
During the execution of vc_build.bat the script tries to infer some of the environment settings that are being used for compilation. Those "findings" are saved to the setBuildEnvVars.bat file, which is loaded by vc_build.bat prior to compile external libraries. It will also be used when running regression tests or building the documentation, as described on sections 5 and 6.
If you have any trouble compiling the mimalloc or the Lis external libraries during your first call to vc_build.bat, check that the values stored in setBuildEnvVars.bat are consistent. If not, create a userConfig.bat file to correct them following the instructions found on the setBuildEnvVars.bat file header.
The vc_build.bat command accepts several optional flags. Use vc_build.bat -h to list them all. Usually none of them is required on a daily basis.
3.3) From the command line, type gema.sln or devenv gema.sln depending on your Visual Studio configuration. This will open the GeMA solution in Visual Studio with the correct environment set.
3.3.1) (VS 2022 only) The qmake tool creates projects for Visual studio 2019. At the end of the vc_build step, when targeting VS 2022, the generated projects are automatically retargeted to the 2022 version by updating the generated .vcxproj files. If, for some reason, this causes any trouble, this retargetting can be disabled with the -noretarget option. If you do that, you will need to manually retarget the projects by clicking in the menu "Project > Retarget Solution". You will need to do that EVERY TIME the vc_build.bat command is executed.
3.3.2) (VS 2022 with 2019 compiler only) When you first open the solution, Visual studio will ask you if you want to retarget the solution to 2022. Just select the don't retarget option. This will be a one time only operation.
3.4) Now just do a common Visual Studio release and debug builds and everything needed should be compiled and copied to the correct places.
3.5) To build the gemaMonitor GUI application, repeat steps 3.3 and 3.4 using the gemaMonitor.sln file.
3.6) To make the build process simpler, HDF5 library files are precompiled in the repository for Visual Studio 2017 x64. Those libraries can be used to build GeMA with Visual studio 2017, 2019 and 2022. If, for some reason, you need to recompile those libraries, check the README file on ext\hdf5 for instructions on how to build. The needed steps are easy enough, but installing CMake is necessary.
3.7) Both the Armadillo and SuperLU libraries used by GeMA require a BLAS/LAPACK distribution to work. GeMA uses by default the OpenBlas library, but it can be compiled with Intel Mkl or with the original blas/lapack distributions. To change the default, use the -blas option when calling vc_build.bat. It requires a library name parameter. Use vc_build.bat -h to see the available lib option names. The Suite sparse library also makes use of blas and, at the moment, the current compilation only works with the openBlas option :(
That should not be very hard to change though.
If you want to enable some unit tests in your GeMA build, just run vc_build.bat -tests. Keep in mind that building with unit tests can only be done in debug mode and they take a long time. So this option is a development only option.
If you are not going to develop code with GeMA and want to just compile the libraries and the console application, you can just run vc_build.bat -rebuild in step 3.2 and skip the other two steps.
After compiling the code (in release mode), at the command line, from the source root directory type:
This will run a simple temperature calculation simulation. Results will be printed to the screen and saved to the examples\temperature\out folder. The output can also be found in the file runlog.txt.
Before running the example, please make sure that you have write permission for creating the result file.
Regression tests can be executed by simply executing the runTests.bat file on the gema\regressionTests folder. Running those tests in debug mode can be done by calling runTests.bat -debug (running the tests in debug mode can take hours!)
When calling runTests.bat the environment for running GeMA is prepared by executing the setBuildEnvVars.bat file on the root folder. This file is generated by the call to vc_build.bat (step 3.2) on every time that it is run, so don't change it. If for some reason the paths on that file are incorrect, you can create your own userConfig.bat file with the correct information, as described in the comments on setBuildEnvVars.bat.
This file (setBuildEnvVars.bat) is also used when compiling the project or when setting up the environment for building the docs (step 6).
The GeMA documentation is built with the Doxygen tool.
The first step is to download and install the doxygen tool from www.doxygen.org. It is also necessary to install the Graphviz package from www.graphviz.org (the Dot tool from that package is needed by Doxygen to create class and collaboration diagrams).
Tip: Doxygen version 1.8.16 has trouble with some headers and is generating incorrect documentation. Version 1.8.15 seems to be working ok.
Next, follow the instructions on the README.txt file on the doxygenScripts folder. If you have any trouble with paths or with the location of the Dot tool from the Graphviz package, create your own userConfig.bat file as explained on section 5.
After this four steps, the documentation can be created by simply running the DoxygenBuild.bat file on the root directory.
When updating the docs, it is useful to just run the DoxygenBuild.bat file from the changed docs folder, since the whole build process is lengthy. For example, if you changed the documentation for the HydroFemPhysics plugin in plugins\physics\hydroFemPhysics\doxygen, run the DoxygenBuild.bat file at plugins\physics\hydroFemPhysics.
This partial update procedure is essential while writting the docs, but this might break some connections between each project docs, so when building the whole documentation, remember to run the DoxygenClear and DoxygenBuild bats from the root directory.
To deploy the site, use the DoxygenCopy.bat to extract the whole documentation to a temporary folder (set the destination on the beginning of the batch file). Afterwards, the whole contents of the folder should be copied to the server.
1.12.0